package com.lx.service;

import com.lx.dto.*;
import retrofit2.Call;
import retrofit2.http.Body;
import retrofit2.http.GET;
import retrofit2.http.POST;
import retrofit2.http.Query;

/**
 * 微信API服务
 */
public interface IWeixinApiService {
    /**
     * 获取 Access token
     * AccessToken是公众号的全局唯一接口调用凭据，公众号调用各接口时都需使用access_token
     * 文档：https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_access_token.html
     *
     * @param grantType 获取access_token填写client_credential
     * @param appId     第三方用户唯一凭证
     * @param appSecret 第三方用户唯一凭证密钥，即appsecret
     * @return 响应结果
     */
    @GET("cgi-bin/token")
    Call<WeixinTokenResponseDTO> getToken(
            @Query("grant_type") String grantType,
            @Query("appid") String appId,
            @Query("secret") String appSecret
    );

    /**
     * 获取凭据 ticket
     * 通过 AccessToken 获取 ticket 凭证，凭证用于衔接用户扫码登录和公众号回调后获取凭证，以此关联用户登录信息。通过 ticket 传递给前端，前端页面访问微信地址直接获取二维码。
     * 文档：https://developers.weixin.qq.com/doc/offiaccount/Account_Management/Generating_a_Parametric_QR_Code.html
     * <a href="https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET">前端根据凭证展示二维码</a>
     *
     * @param accessToken            getToken 获取的 token 信息
     * @param weixinQrCodeRequestDTO 入参对象
     * @return 应答结果
     */
    @POST("cgi-bin/qrcode/create")
    Call<WeixinQrCodeResponseDTO> createQrCode(@Query("access_token") String accessToken, @Body WeixinQrCodeRequestDTO weixinQrCodeRequestDTO);


    /**
     * 第一步：用户同意授权，获取code
     * 接口：https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect
     * 文档：https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
     *
     * @param appid        公众号的唯一标识
     * @param redirectUri  授权后重定向的回调链接地址， 请使用 urlEncode 对链接进行处理
     * @param responseType 返回类型，请填写code
     * @param scope        应用授权作用域，snsapi_base （不弹出授权页面，直接跳转，只能获取用户openid），snsapi_userinfo （弹出授权页面，可通过openid拿到昵称、性别、所在地。并且， 即使在未关注的情况下，只要用户授权，也能获取其信息 ）
     * @param state        重定向后会带上state参数，开发者可以填写a-zA-Z0-9的参数值，最多128字节(非必填)
     * @param forcePopup   强制此次授权需要用户弹窗确认；默认为false；需要注意的是，若用户命中了特殊场景下的静默授权逻辑，则此参数不生效(非必填)
     * @return
     */
    @POST("connect/oauth2/authorize")
    Call<OAuth2AuthorizationCode> getAuthorizationCode(
            @Query("appid") String appid,
            @Query("redirect_uri") String redirectUri,
            @Query("response_type") String responseType,
            @Query("scope") String scope,
            @Query("state") String state,
            @Query("forcePopup") String forcePopup
    );


    /**
     * 第二步：通过code换取网页授权access_token
     * 接口：https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
     * 文档：https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
     *
     * @param appid     公众号的唯一标识
     * @param secret    公众号的appsecret
     * @param code      填写第一步获取的code参数
     * @param grantType 填写为authorization_code
     * @return
     */
    @GET("sns/oauth2/access_token")
    Call<OAuth2AuthorizationToken> authorizationAccessToken(
            @Query("appid") String appid,
            @Query("secret") String secret,
            @Query("code") String code,
            @Query("grant_type") String grantType
    );

    /**
     * 第三步：刷新access_token（如果需要）
     * 由于access_token拥有较短的有效期，当access_token超时后，可以使用refresh_token进行刷新，refresh_token有效期为30天，当refresh_token失效之后，需要用户重新授权。
     * 接口：https://api.weixin.qq.com/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
     * 文档：https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
     *
     * @param appid        公众号的唯一标识
     * @param grantType    填写为refresh_token
     * @param refreshToken 填写通过access_token获取到的refresh_token参数
     * @return
     */
    @GET("sns/oauth2/refresh_token")
    Call<OAuth2AuthorizationToken> authorizationRefreshToken(
            @Query("appid") String appid,
            @Query("grant_type") String grantType,
            @Query("refresh_token") String refreshToken
    );


    /**
     * 第四步：拉取用户信息(需scope为 snsapi_userinfo)
     * 接口：https://api.weixin.qq.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN
     * 文档：https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
     *
     * @param accessToken 网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
     * @param openid      用户的唯一标识
     * @param lang        返回国家地区语言版本，zh_CN 简体，zh_TW 繁体，en 英语
     * @return
     */
    @GET("sns/userinfo")
    Call<UserInfoResponseDTO> getAuthorizationUserInfo(
            @Query("access_token") String accessToken,
            @Query("openid") String openid,
            @Query("lang") String lang
    );

    /**
     * 检验授权凭证（access_token）是否有效
     * 接口：https://api.weixin.qq.com/sns/auth?access_token=ACCESS_TOKEN&openid=OPENID
     * 文档：https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
     *
     * @param accessToken 网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
     * @param openid      用户的唯一标识
     * @return
     */
    @GET("sns/auth")
    Call<OAuth2AuthorizationToken> getAuthorizationAuth(
            @Query("access_token") String accessToken,
            @Query("openid") String openid
    );


}
